<!DOCTYPE html>
<html lang="cn" class="js csstransforms3d">
  <head>
    <meta charset="utf-8">
    <meta name="viewport" content="width=device-width, initial-scale=1, maximum-scale=1, user-scalable=no">
    <meta http-equiv="Cache-Control" content="max-age=7200" />
    <meta name="generator" content="Hugo 0.37.1" />
    <meta name="description" content="">


    <link rel="shortcut icon" href="https://shardingsphere.apache.org/document/current/img/favicon.png" type="image/x-icon" />

    <title>开发规范 :: ShardingSphere</title>
    
    
    <link href="https://shardingsphere.apache.org/community/css/nucleus.css?1584863738" rel="stylesheet">
    <link href="https://shardingsphere.apache.org/community/css/font-awesome.min.css?1584863738" rel="stylesheet">
    <link href="https://shardingsphere.apache.org/community/css/hybrid.css?1584863738" rel="stylesheet">
    <link href="https://shardingsphere.apache.org/community/css/featherlight.min.css?1584863738" rel="stylesheet">
    <link href="https://shardingsphere.apache.org/community/css/perfect-scrollbar.min.css?1584863738" rel="stylesheet">
    <link href="https://shardingsphere.apache.org/community/css/auto-complete.css?1584863738" rel="stylesheet">
    <link href="https://shardingsphere.apache.org/community/css/theme.css?1584863738" rel="stylesheet">
    <link href="https://shardingsphere.apache.org/community/css/hugo-theme.css?1584863738" rel="stylesheet">
    
      <link href="https://shardingsphere.apache.org/community/css/theme-black.css?1584863738" rel="stylesheet">
    

    <script src="https://shardingsphere.apache.org/community/js/jquery-2.x.min.js?1584863738"></script>
    
    <style type="text/css">
      :root #header + #content > #left > #rlblock_left{ 
          display:none !important;
      }
      
    </style>
    

  </head>
  <body class="" data-url="/cn/contribute/code-conduct/">
    <nav id="sidebar" class="">



  <div id="header-wrapper">
    <div id="header">
      <a href="https://shardingsphere.apache.org/"><img src="https://shardingsphere.apache.org/document/current/img/logo_v2.png" /></a>

    </div>
    
  </div>

    <div class="highlightable">
    <ul class="topics">

        
          
          


 
  
    
    <li data-nav-id="/cn/contribute/" title="参与和贡献" class="dd-item 
        parent
        
        
        ">
      <a href="https://shardingsphere.apache.org/community/cn/contribute/">
          <b>1. </b>参与和贡献
          
      </a>
      
      
        <ul>
          
          
          
          
        
          
            
            


 
  
    
      <li data-nav-id="/cn/contribute/subscribe/" title="订阅指南" class="dd-item ">
        <a href="https://shardingsphere.apache.org/community/cn/contribute/subscribe/">
        订阅指南
        
        </a>
    </li>
     
  
 

            
          
            
            


 
  
    
      <li data-nav-id="/cn/contribute/contributor/" title="贡献者指南" class="dd-item ">
        <a href="https://shardingsphere.apache.org/community/cn/contribute/contributor/">
        贡献者指南
        
        </a>
    </li>
     
  
 

            
          
            
            


 
  
    
      <li data-nav-id="/cn/contribute/committer/" title="提交者指南" class="dd-item ">
        <a href="https://shardingsphere.apache.org/community/cn/contribute/committer/">
        提交者指南
        
        </a>
    </li>
     
  
 

            
          
            
            


 
  
    
      <li data-nav-id="/cn/contribute/code-conduct/" title="开发规范" class="dd-item active">
        <a href="https://shardingsphere.apache.org/community/cn/contribute/code-conduct/">
        开发规范
        
        </a>
    </li>
     
  
 

            
          
            
            


 
  
    
      <li data-nav-id="/cn/contribute/document-contributor/" title="官方文档贡献指南" class="dd-item ">
        <a href="https://shardingsphere.apache.org/community/cn/contribute/document-contributor/">
        官方文档贡献指南
        
        </a>
    </li>
     
  
 

            
          
            
            


 
  
    
      <li data-nav-id="/cn/contribute/release/" title="发布指南" class="dd-item ">
        <a href="https://shardingsphere.apache.org/community/cn/contribute/release/">
        发布指南
        
        </a>
    </li>
     
  
 

            
          
            
            


 
  
    
      <li data-nav-id="/cn/contribute/2fa/" title="2FA" class="dd-item ">
        <a href="https://shardingsphere.apache.org/community/cn/contribute/2fa/">
        2FA
        
        </a>
    </li>
     
  
 

            
          
        
        </ul>
              
    </li>
  
 

          
          


 
  
    
    <li data-nav-id="/cn/powered-by/" title="采用公司" class="dd-item 
        
        
        
        ">
      <a href="https://shardingsphere.apache.org/community/cn/powered-by/">
          <b>2. </b>采用公司
          
      </a>
      
              
    </li>
  
 

          
          


 
  
    
    <li data-nav-id="/cn/team/" title="团队" class="dd-item 
        
        
        
        ">
      <a href="https://shardingsphere.apache.org/community/cn/team/">
          <b>3. </b>团队
          
      </a>
      
              
    </li>
  
 

          
          


 
  
    
    <li data-nav-id="/cn/security/" title="安全" class="dd-item 
        
        
        
        ">
      <a href="https://shardingsphere.apache.org/community/cn/security/">
          <b>4. </b>安全
          
      </a>
      
              
    </li>
  
 

          
         
    </ul>

    
    

    
    <section id="prefooter">
      <hr/>
      <ul>
      
        <li>
          <a class="padding">
            <i class="fa fa-fw fa-language"></i>
          <div class="select-style">
            <select id="select-language" onchange="location = this.value;">
          
          
          
              
              
                  
                    
                    
<option id="en" value="/community/en/contribute/code-conduct/">English</option>
                    
                  
              
                  
              
          
              
              
                  
              
                  
                    
                    
<option id="cn" value="/community/cn/contribute/code-conduct/" selected>Chinese</option>
                    
                  
              
          
        </select>
        <svg version="1.1" id="Capa_1" xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" x="0px" y="0px"
          width="255px" height="255px" viewBox="0 0 255 255" style="enable-background:new 0 0 255 255;" xml:space="preserve">
          <g>
            <g id="arrow-drop-down">
              <polygon points="0,63.75 127.5,191.25 255,63.75 		" />
            </g>
          </g>
        </svg>
        </div>
        </a>
        </li>
       
      
      
      </ul>
    </section>
    
    <section id="footer">
      <p></p>

    </section>
  </div>
</nav>





        <section id="body">
        <div id="overlay"></div>
        <div class="padding highlightable">
              
              <div>
                <div id="top-bar">
                
                
                <div id="breadcrumbs" itemscope="" itemtype="http://data-vocabulary.org/Breadcrumb">
                    <span id="sidebar-toggle-span">
                        <a href="#" id="sidebar-toggle" data-sidebar-toggle="">
                          <i class="fa fa-bars"></i>
                        </a>
                    </span>
                  
                  <span class="links">
                    
          
          
            
            
          
          
            
            
          
          
            <a href='https://shardingsphere.apache.org/community/cn/'>ShardingSphere</a> > <a href='https://shardingsphere.apache.org/community/cn/contribute/'>参与和贡献</a> > 开发规范
          
         
          
         
          
           
                  </span>
                </div>
                
              </div>
            </div>
            

        
          <div id="chapter">
        
        <div id="body-inner">
          

        




<p>以下行为准则以完全遵循<a href="https://www.apache.org/foundation/policies/conduct.html">Apache软件基金会行为准则</a>为前提。</p>

<h2 id="开发理念">开发理念</h2>

<ul>
<li><strong>用心</strong> 保持责任心和敬畏心，以工匠精神持续雕琢。</li>
<li><strong>可读</strong> 代码无歧义，通过阅读而非调试手段浮现代码意图。</li>
<li><strong>整洁</strong> 认同《重构》和《代码整洁之道》的理念，追求整洁优雅代码。</li>
<li><strong>一致</strong> 代码风格、命名以及使用方式保持完全一致。</li>
<li><strong>精简</strong> 极简代码，以最少的代码表达最正确的意思。高度复用，无重复代码和配置。及时删除无用代码。</li>
<li><strong>抽象</strong> 层次划分清晰，概念提炼合理。保持方法、类、包以及模块处于同一抽象层级。</li>
<li><strong>极致</strong> 拒绝随意，保证任何一行代码、任何一个字母、任何一个空格都有其存在价值。</li>
</ul>

<h2 id="代码提交行为规范">代码提交行为规范</h2>

<ul>
<li>确保通过全部测试用例，确保执行<code>./mvnw clean install</code>可以编译和测试通过。</li>
<li>确保覆盖率不低于master分支。</li>
<li>确保使用Checkstyle检查代码，违反验证规则的需要有特殊理由。模板位置在<code>https://github.com/apache/incubator-shardingsphere/blob/master/src/resources/checkstyle.xml</code>，请使用checkstyle 8.8运行规则。</li>
<li>应尽量将设计精细化拆分；做到小幅度修改，多次数提交，但应保证提交的完整性。</li>
<li>确保遵守编码规范。</li>
</ul>

<h2 id="编码规范">编码规范</h2>

<ul>
<li>使用linux换行符。</li>
<li>缩进（包含空行）和上一行保持一致。</li>
<li>类声明后与下面的变量或方法之间需要空一行。</li>
<li>不应有无意义的空行。</li>
<li>类、方法和变量的命名要做到顾名思义，避免使用缩写。</li>
<li>返回值变量使用<code>result</code>命名；循环中使用<code>each</code>命名循环变量；map中使用<code>entry</code>代替<code>each</code>。</li>
<li>捕获的异常名称命名为<code>ex</code>；捕获异常且不做任何事情，异常名称命名为<code>ignored</code>。</li>
<li>配置文件使用驼峰命名，文件名首字母小写。</li>
<li>需要注释解释的代码尽量提成小方法，用方法名称解释。</li>
<li><code>equals</code>和<code>==</code>条件表达式中，常量在左，变量在右；大于小于等条件表达式中，变量在左，常量在右。</li>
<li>除了构造器入参与全局变量名称相同的赋值语句外，避免使用<code>this</code>修饰符。</li>
<li>除了用于继承的抽象类之外，尽量将类设计为<code>final</code>。</li>
<li>嵌套循环尽量提成方法。</li>
<li>成员变量定义顺序以及参数传递顺序在各个类和方法中保持一致。</li>
<li>优先使用卫语句。</li>
<li>类和方法的访问权限控制为最小。</li>
<li>方法所用到的私有方法应紧跟该方法，如果有多个私有方法，书写私有方法应与私有方法在原方法的出现顺序相同。</li>
<li>方法入参和返回值不允许为<code>null</code>。</li>
<li>优先使用三目运算符代替if else的返回和赋值语句。</li>
<li>优先使用lombok代替构造器，getter, setter方法和log变量。</li>
<li>优先考虑使用<code>LinkedList</code>，只有在需要通过下标获取集合中元素值时再使用<code>ArrayList</code>。</li>
<li><code>ArrayList</code>，<code>HashMap</code>等可能产生扩容的集合类型必须指定集合初始大小，避免扩容。</li>
<li>日志与注释一律使用英文。</li>
<li>注释只能包含javadoc，todo和fixme。</li>
<li>公开的类和方法必须有javadoc，其他类和方法以及覆盖自父类的方法无需javadoc。</li>
</ul>

<h2 id="单元测试规范">单元测试规范</h2>

<ul>
<li>测试代码和生产代码需遵守相同代码规范。</li>
<li>单元测试需遵循AIR（Automatic, Independent, Repeatable）设计理念。

<ul>
<li>自动化（Automatic）：单元测试应全自动执行，而非交互式。禁止人工检查输出结果，不允许使用<code>System.out</code>，<code>log</code>等，必须使用断言进行验证。</li>
<li>独立性（Independent）：禁止单元测试用例间的互相调用，禁止依赖执行的先后次序。每个单元测试均可独立运行。</li>
<li>可重复执行（Repeatable）：单元测试不能受到外界环境的影响，可以重复执行。</li>
</ul></li>
<li>单元测试需遵循BCDE（Border, Correct, Design, Error）设计原则。

<ul>
<li>边界值测试（Border）：通过循环边界、特殊数值、数据顺序等边界的输入，得到预期结果。</li>
<li>正确性测试（Correct）：通过正确的输入，得到预期结果。</li>
<li>合理性设计（Design）：与生产代码设计相结合，设计高质量的单元测试。</li>
<li>容错性测试（Error）：通过非法数据、异常流程等错误的输入，得到预期结果。</li>
</ul></li>
<li>如无特殊理由，测试需全覆盖。</li>
<li>每个测试用例需精确断言。</li>
<li>准备环境的代码和测试代码分离。</li>
<li>只有junit <code>Assert</code>，hamcrest <code>CoreMatchers</code>，Mockito相关可以使用static import。</li>
<li>单数据断言，应使用<code>assertTrue</code>，<code>assertFalse</code>，<code>assertNull</code>和<code>assertNotNull</code>。</li>
<li>多数据断言，应使用<code>assertThat</code>。</li>
<li>精确断言，尽量不使用<code>not</code>，<code>containsString</code>断言。</li>
<li>测试用例的真实值应名为为actualXXX，期望值应命名为expectedXXX。</li>
<li>测试类和<code>@Test</code>标注的方法无需javadoc。</li>
</ul>

<h2 id="g4编码规范">G4编码规范</h2>

<ul>
<li>公共规范

<ul>
<li>每行长度不超过<code>200</code>个字符，保证每一行语义完整以便于理解。</li>
</ul></li>
<li>词法解析规范

<ul>
<li>每个规则一行，规则间无需空行。</li>
<li>规则名称使用大写字母。如果名称由多个单词组成，用<code>下划线</code>间隔。<code>DataType</code>和<code>Symbol</code>的规则命名以<code>下划线</code>结尾。与ANTLR内置变量或关键字重名的规则在结尾加<code>下划线</code>以示区分。</li>
<li>不对外暴露的规则使用<code>fragment</code>，<code>fragment</code>定义的规则需在其服务的规则之后声明。</li>
<li>公用规则定义放在<code>Keyword.g4</code>，每个数据库可以有自己特有的规则定义。例如：<code>MySQLKeyword.g4</code>。</li>
</ul></li>
<li>语法解析规范

<ul>
<li>每个规则结束后空一行，空行无需缩进。</li>
<li>规则名称前面不空格，<code>冒号</code>后空一格再开始写规则，<code>分号</code>在单独一行并保持和上一行相同缩进。</li>
<li>如果一个规则的分支超过<code>5</code>个，则每个分支一行。</li>
<li>规则命名采用java变量的驼峰形式。</li>
<li>为每种SQL语句类型定义一个独立的语法文件，文件名称由<code>数据库名称</code> + <code>语句类型名称</code> + <code>Statement</code>。例如：<code>MySQLDQLStatement.g4</code>。</li>
</ul></li>
</ul>


<footer class=" footline" >
	
</footer>


        
            </div> 
        
        </div> 
        

      </div>

    <div id="navigation">
        
        
        
        
            
            
                
                    
                    
                
                

                    
                    
                        
                    
                    

                    
                        
            
            
                
                    
                    
                
                

                    
                    
                    

                    
                        
            
            
                
                    
                        
                        
                    
                
                

                    
                    
                    

                    
            
        
                    
                        
            
            
                
                    
                
                

                    
                    
                    

                    
            
        
                    
                        
            
            
                
                    
                
                

                    
                    
                    

                    
            
        
                    
                        
            
            
                
                    
                    
                
                

                    
                    
                    

                    
            
        
                    
                        
            
            
                
                    
                        
                        
                    
                
                

                    
                    
                    

                    
            
        
                    
                        
            
            
                
                    
                
                

                    
                    
                    

                    
            
        
                    
                        
            
            
                
                    
                
                

                    
                    
                    

                    
            
        
                    
            
        
                    
                        
            
            
                
                    
                
                

                    
                    
                    

                    
            
        
                    
                        
            
            
                
                    
                
                

                    
                    
                    

                    
            
        
                    
                        
            
            
                
                    
                
                

                    
                    
                    

                    
            
        
                    
            
        
        
        


        
            <a class="nav nav-prev" href="https://shardingsphere.apache.org/community/cn/contribute/committer/" title="提交者指南"> <i class="fa fa-chevron-left"></i></a>
        
        
            <a class="nav nav-next" href="https://shardingsphere.apache.org/community/cn/contribute/document-contributor/" title="官方文档贡献指南" style="margin-right: 0px;"><i class="fa fa-chevron-right"></i></a>
        
    </div>

    </section>
    
    <div style="left: -1000px; overflow: scroll; position: absolute; top: -1000px; border: none; box-sizing: content-box; height: 200px; margin: 0px; padding: 0px; width: 200px;">
      <div style="border: none; box-sizing: content-box; height: 200px; margin: 0px; padding: 0px; width: 200px;"></div>
    </div>
    <script src="https://shardingsphere.apache.org/community/js/clipboard.min.js?1584863738"></script>
    <script src="https://shardingsphere.apache.org/community/js/perfect-scrollbar.min.js?1584863738"></script>
    <script src="https://shardingsphere.apache.org/community/js/perfect-scrollbar.jquery.min.js?1584863738"></script>
    <script src="https://shardingsphere.apache.org/community/js/jquery.sticky.js?1584863738"></script>
    <script src="https://shardingsphere.apache.org/community/js/featherlight.min.js?1584863738"></script>
    <script src="https://shardingsphere.apache.org/community/js/html5shiv-printshiv.min.js?1584863738"></script>
    <script src="https://shardingsphere.apache.org/community/js/highlight.pack.js?1584863738"></script>
    <script>hljs.initHighlightingOnLoad();</script>
    <script src="https://shardingsphere.apache.org/community/js/modernizr.custom.71422.js?1584863738"></script>
    <script src="https://shardingsphere.apache.org/community/js/learn.js?1584863738"></script>
    <script src="https://shardingsphere.apache.org/community/js/hugo-learn.js?1584863738"></script>

    <link href="https://shardingsphere.apache.org/community/mermaid/mermaid.css?1584863738" type="text/css" rel="stylesheet" />
    <script src="https://shardingsphere.apache.org/community/mermaid/mermaid.js?1584863738"></script>
    <script>
        mermaid.initialize({ startOnLoad: true });
    </script>
    

  </body>
</html>

